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1.0  INTRODUCTION 


Microcomputer  "programming  is  a  labor-intensive  manufac¬ 
turing  process"  (Lewis,  1979).  Each  year  the  Department  of 
Defense  (DoD)  spends  billions  of  dollars  on  all  kinds  of  macro- 
and  minicomputer  software  projects,  hundreds  of  millions  on 
microcomputer  programming,  but  relatively  little  on  software 
engineering,  documentation,  and  evaluation  research.  This  report 
thus  focuses  upon  several  approaches  and  techniques  designed  to 
improve  the  processes  by  which  we  program  microcomputers,  docu¬ 
ment  microcomputer  software,  and  evaluate  software  quality  and 
performance--all  with  reference  to  DoD  research  and  development 
needs,  requirements,  and  priorities. 

Section  2.0  of  this  report  presents  techniques  for  enhanced 
microcomputer  software  engineering.  Section  3.0  looks  at  several 
useful  microcomputer  software  documentation  techniques,  while 
Section  4.0  presents  a  multi-attribute  utility-based  model  for 
software  evaluation. 
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2.0  MICROCOMPUTER  SOFTWARE  ENGINEERING 


2 . 1  Requirements 

Ideally  before  one  attempts  to  build  a  microcomputer  pro¬ 
gram  an  effort  is  made  to  identify  and  define  the  driving 
functional  requirements  which  together  comprise  the  reason (s) 
why  one  attempts  to  build  a  problem-solving  software  system 
(instead  of  some  other  kind  of  problem-solving  system) . 

At  the  most  basic  level  are  several  requirements  which  are 
specific  context  and  applications  independent;  that  is,  they 
are  relevant  to  all  instances  of  microcomputer  programming 
regardless  of  for  whom  and/or  what  the  software  is  to  be  devel¬ 
oped  . 


2.1.1  Response  Time  -  The  first  is  response  time.  Note 
that  the  issue  here  is  not  how  fast  or  slowly  the  system  responds 
to  a  particular  user  vis-a-vis  a  particular  task,  but  how  fast 
or  slowly  it  responds  generally.  This  kind  of  speed  (or  slowness) 
is  a  function  of  the  software  language  used  and  the  microcomputer 
system  I/O  device  times.  The  figure  below,  from  Barden  (1979), 
presents  the  total  response  time  for  some  standard  I/O  operations. 


Operation 

I/O  Device 

Time 

Print  line  of  64  characters. 

Teletype 

7  seconds 

Print  line  of  64  characters 

IBM  Selednc 

4  seconds 

Print  Ime  of  64  characters. 

Dot-matrix 

electrosensitive  printer 

1-2  seconds 

Pnnt  line  of  64  characters 

Dot-matrix 
impact  printer 

1-2  seconds 

Display  1024  characters 

Video  display 

1  second 

(entire  screen 

interface 

Display  1024  character 
(ent  re  screen 

Crt  terminal 

2  seconds 

Read  or  write  one  100-character 

Audio  tape  cassette 

2  mmutes 

recofd  randomly  on  tape 

with  automate  or 

manual  sea*ch 

Read  or  write  one  100-character 

Audio  tape  cassette 

record  to  nex*  pOS'*'On  on  tape 

30  cps 

5  seconds 

2C0  cps 

3  seconds 

Read  or  write  one  1 28-character 

Small  floppy  disk  (5  in) 

*'2  second 

reco'd  randomly  on  floppy  d  sl 

Large  floppy  d>sk  (8  in 

’  3  second 

Read  or  write  one  128  charade' 

Small  flopp »  disk 

c'ose  to  0 

reco'd  to  next  pos  t.on  on  g.*> 

Large  floppy  d  s* 

I/O  Operation  Time 


But  many  operations  are  non- I/O-oriented ,  depending  instead 
upon  the  skill  of  the  programmer  and  efficiency  of  the  program, 
which,  in  turn,  depends  upon  the  characteristics  of  the  language 
used  and  whether  or  not  the  (higher- level )  language  is  compiled 
or  interpreted  in  operation,  as  suggested  below  (Barden,  1979). 


3 


Function 

Astembiy- 

Langgagi 

System 

Compiler* 

language 

System 

Interpreter* 

Language 

System 

Multiply  1000  numbers  of 

various  sizes 

1  ms 

6  ms 

6  s 

Divide  1000  numbers  of 

vinous  sizes 

1 .5  ms 

9  ms 

9s 

Insert  a  20-character  string  in 
the  middle  of  1000  characters 

of  text 

7.5  ms 

75  ms 

10s 

Sort  (alphabetize}  a  list  of  100 
20character  names 

0  1  s 

2  s 

8  min 

Merge  20  names  tn?o  a  list  of 

100  20-character  names 

25  ms 

0  5s 

2  min 

Search  100  20  character  ran- 

dom-'y  ordered  names 

4  ms 

40  ms 

15s 

Search  100  20-character  alpha 
hewed  (O'  otherw-se  ordered’ 

names 

0.4  ms 

4  ms 

1.5  s 

Processing  Response  Times 


2.1.2  Operating 
processing  time.  But 
the  software  languages 
course,  the  efficiency 


Time  -  Operating  time  equals  I/O  time  and 
the  processing  time  is  always  dependent  upon 
used,  the  form  of  the  language,  and,  of 
of  the  programmer,  all  as  suggested  below 


(Barden ,  1979). 


Application 

Assembly- 

language 

System 

Compiler- 

Language 

System 

Interpreter 

language 

System 

Sort  end  print  1000  nemes  for 
mailing  list,  100  characters/ 
entry,  disk  system 

25  min 

25  min 

105  min 

Generate  inventory  report  of 
1000  items.  100  characters' 
item,  disk  system 

25  min 

30  min 

41  min 

Response  time  for  locating  and 
display  of  one  random  account 
from  2000,  disk  system 

5  » 

5  > 

30 » 

Application  Operating  Timas 
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2.1.3  Program  Status  -  Another  requirement  has  to  do  with 
the  status  of  the  program  to  be  developed.  Programs  which  are 


fundamentally  prototypical  or  experimental  usually  bear  no 
resemblance  to  production  (systems  or  applications)  programs. 
Similarly  most  programs  developed  as  an  initial  outgrowth  of 
research  and  development  are  iterative  in  their  evolution  and 
should  therefore  be  developed  differently  from  programs  intended 
for  wide  distribution  and  use. 

2.1.4  Support  Requirements  -  Not  unrelated  to  all  of  the 
above  are  support  requirements.  Is  the  program  to  be  transferred 
for  on-line  use?  Or  is  it  to  be  used  off-line  by  research  and 
development  counterparts?  Such  questions  determine  to  what 
extent  the  software  must  be  self-contained,  among  other  consider¬ 
ations. 

2 . 2  Microcomputer  Software  Languages 

Response  and  operating  time  requirements,  the  status  of 
the  program,  and  support  requirements,  among  many  other  conceiv¬ 
able  requirements,  should  determine  the  selection  of  a  software 
language.  Indeed,  a  set  of  guidelines  regarding  the  use  of  one 
or  more  languages,  of  the  nature  presented  below,  should  be 
developed  and  u^  dated  frequently  in  order  to  ensure  the  most 
prudent  and  practical  use  of  one  or  another  language.  In  any  case 
the  first  task  is  to  understand  the  relationships  among  the  dif- 


ferent  types  of  software,  as  presented  below  (Frenzel,  1979). 


Interrelationships  between  different  types  of  software 

In  addition  to  such  relationships  are  those  which  surround  the 
requirements,  available  capabilities,  and  optimal  language 
selection.  (Note  that  for  the  purposes  of  this  exemplar  exercise 
substantive  requirements  are  not  suggested  since  they  differ 
from  case  to  case.)  For  example, 

•  UL  response  time  and  operating  time  is 
important  then  one  should,  assuming 
programming  competence,  use  compiler 
rather  than  interpretive  languages  for 
production  systems; 

•  If  a  system  is  by  definition  iterative 
then  interpretive  languages  should  be 
utilized;  and 


•  I_f  the  talent  (capability)  exists,  then 
machine  and  assembly  languages  shouT3 
be  used  to  maximize  the  speed  of  pro¬ 
duction  systems,  and  so  forth. 

The  point  here  is  that  based  upon  existing  empirical  studies 
it  is  possible  to  develop  sets  of  guidelines  about  the  selection 
of  software  programming  languages  against  explicit  requirements. 
Such  guidelines  might  even  be  computerized  in  a  developmental 
reference  system  which  could  be  used  by  research  and  development 
managers,  programmers,  and  higher-level  decision-makers  who  must 
make  major  software  investment  decisions.  Such  a  production 
rule  system  would  make  systematic  a  selection  process  that  is 
now  dominated  by  preference  and  accessibility . 

2 . 3  Programming  Methods 

It  is  difficult  to  list  or  define  the  myriad  methods  now 
utilized  by  programmers.  Candidly,  most  do  not  have  methods 
which  are  reproducible  (even  by  themselves)  or  verifiable. 

Instead,  they  usually  begin  with  what  they  perceive  to  be  the 
pivotal  processing  function  and  they  build  around  it.  Most 
seldom  even  flow-chart  what  they  intend  to  program. 

Proposed  below  are  several  structuring  techniques  designed 
specifically  to  improve  microcomputer  programming  (also  see 
Appendix  A  for  a  reprint  of  an  article  on  structured  programming). 
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In  reality  they  are  presented  to  avoid  scenarios  like  the  fol¬ 
lowing  (Lewis,  1979): 


Peter  Plodder  u  slow,  methodical,  and  very  meticulous.  A  mild- 
mannered,  quiet  person  (with  good  taste  in  clothes/,  he  had  the  irritating 
habit  of  issuing  long  project  completion  limes  to  his  supervisor.  Bluster¬ 
ing  Barton,  on  the  other  hand,  was  a  flashy,  outspoken  superprogrammer 
who  consistently  completed  his  programming  assignments  ahead  of  the 
most  optimistic  estimates. 

The  Software  Divtsion  management  loved  Blust.  but  hardly  knew 
Peter  was  alive.  Consequently,  Blust  was  granted  a  six-month  leave  of 
absence — a  biscuit  for  his  programming  accomplishments.  A  temporary 
programmer  was  hired  to  maintain  Blust's  code  while  he  was  away. 

Six  weeks  after  Barton  embarked  on  a  plane  for  Africa,  his  payroll 
system  program  failed  The  substitute  programmer  immediately  plunged 
into  Barton  's  program  to  try  to  isolate  the  bug  Perhaps  not  so  surpris¬ 
ingly.  he  was  never  able  to  break  into  the  code.  In  Blustering  Barton's 
race  to  produce  code,  he  neglected  to  write  easy-to-understand  programs, 
and  his  documentation  was  a  mess.  In  short,  only  Barton  himself  could 
repair  the  programs  he  had  written. 

Meanwhile,  back  at  the  desk  of  Peter  Plodder  business  was  progress¬ 
ing  as  usual  Orgammtion  and  clearly  documented  programs  were  his 
trademark  In  fact,  Peter  was  called  on  to  try  to  find  the  bug  m  Barton's 
pay  roll  program  His  time  estimate  for  the  debugging  task  was  customar¬ 
ily  protracted,  but  the  management  had  nochoice.  With  Blustering  Barton 
away  and  the  temporary  programmer  stymied,  they  had  to  go  with  Peter. 

Eventually  the  bug  was  located  and  corrected,  but  everyone  knew 
the  SupeTprog-ta.mrrj.er  had  stumbled.  Summarily ,  neu  programming 
standards  were  implemented  Peter  u-a-s  invited  to  teach  the  other  pro¬ 
grammers  how  to  write  readable  code  He  showed  everyone  (including 
Blustering  Barton,  when  he  returned i  how  to  make  programs  self- 
documenting.  His  methodology  was  adopted  as  the  onl>  acceptable 
meihodolog\  to  be  used  throughout  the  Software  Dwision. 


Sound  familiar?  Unfortunately,  a  great  many  defense  research 
programmers  are  "flashy,  outspoken  superprogrammers"  who  produce 
jumbled,  undocumented  software.  Consequently,  enhancements, 
modifications,  and  technology  transfer  are  all  made  more  diffi¬ 
cult  and  much  more  expensive. 
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2.3.1  Planning  -  Structured  microcomputer  programming  is 
very  similar  to  decision  analysis-based  problem-solving  because 
it  rests  upon  the  principle  of  problem  decomposition  (Williams, 
1981;  Yourdon,  1979;  and  Ross,  et  al.,  1975).  The  functions 
that  the  program  is  to  perform  should  inform  the  decomposition 
process,  and,  much  like  a  multi-attribute  utility  assessment 
structure,  represent  functions  decomposed  to  their  smallest 
component  units.  In  this  way  programmers  can  adhere  to  a  simple 
rule  of  thumb:  software  solutions  should  never  be  more  complex 
than  the  problems  they  are  intended  to  solve. 

2.3.2  Software  Economy  -  Lewis  (1979)  bluntly  states  that 
programmers  should  "never  .vrite  a  large  program."  Instead,  he 
argues  convincingly  that  programmers  should  write  and  collect 
"speedcode  modules"  that  incorporate  all  of  the  basic  algorithms 
which  the  programmer  has  previously  used.  Then  the  modules 
should  be  refined  onto  different  microcomputers  in  different 
languages . 

In  a  previous  report  (Wittmeyer,  1980)  a  design  for  the 

development  of  generic  microcomputer-based  command  and  control 
2 

(C  )  decision  and  forecasting  systems  was  presented  which  was 

based  in  part  upon  the  use  of  pre-programmed  software  modules. 

2 

It  was  even  suggested  that  the  routine  C  decision  and  fore¬ 
casting  systems  functions  probably  numbered  less  than  twenty- 
five.  If  this  is  true  then  a  series  of  modules  (for  retrieving 
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and  displaying  empirical  data,  for  calculating  value,  and  making 
inferences,  and  so  forth)  could  be  developed  and  used  over  and 
over  again.  Similarly,  it  wt  uld  be  possible  to  identify  and 
develop  modules  for  information  management,  training,  and  generic 
information  display. 

Interestingly,  most  defense  software  efforts  begin  from 
ground-zero  and  even  often  ignore  previous  efforts  undertaken 
by  the  attending  programmer!  Clearly  a  great  deal  of  programming 
economy  can  be  gained  by  reviewing  existing  software  and  developing 
reusable  software  modules. 

2.3.3  Software  Psychology  -  All  programming  methodology 
must  be  applied  within  a  particular  personnel  context;  indeed 
all  of  the  above  presumes  the  existence  of  highly  talented, 
dedicated  programmers  who  are  as  knowledgeable  about  hardware 
as  they  are  about  software.  Unfortunately,  virtually  every 
projection  available  today  indicates  that  throughout  the  1980s 
a  critical  shortage  of  programmers  will  persist.  We  must  there¬ 
fore  maximize  the  output  of  those  programmers  which  we  do  employ. 
Learning,  designing,  composition,  comprehension,  testing,  de¬ 
bugging,  documentation,  and  modification  capabilities  must  all 

be  evaluated  and  improved-.  P  e  rhapTg" for— ctre- -f4:-r-s-^-t-ima.f . ^s.e_rd on s  _ 

programming  managers  must  pay  very  special  attention  to  the 
overall  programming  environment,  the  components  of  which  include 
the  physical,  social  and  managerial  environments. 
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2 . 4  Software  Engineering  Guidelines  and  Recommendations 


Requirements  analyses  should  precede  programming.  Require¬ 
ments  should  be  matched  to  software  characteristics ,  and  then 
recommendations  regarding  how  to  write  the  software  should  be 
generated.  In  fact,  there  is  no  reason  why  a  production  rule 
system  such  as  RITA  (Anderson  and  Gillogy,  1976)  could  not  be 
used  for  this  purpose.  Such  a  software  requirements/software 
characteristics/programming  structure  system  might  be  of  invalu¬ 
able  use  to  DARPA  researchers  specifically  and  to  DoD  generally, 
and  might  function  as  follows:  users  could  input  requirements 
consisting  of  operating  and  response  time  requirements,  program 
status  requirements,  support  requirements,  among  any  number  of 
other  requirements  and  the  computer  system,  from  a  knowledge 
base  consisting  of  software  characteristics  (updated  continually) , 
would  then  make  recommendations  regarding  optimal  programming 
efficiency  in  structured  pseudocode  supplemented  by  graphic 
flowcharts  of  same.  It  might  also  suggest  the  use  of  pre-pro¬ 
grammed  software  modules  about  which  it  has  been  given  detailed 
information.  The  information  about  software  form  and  language 
characteristics  could  be  consensus  "expert"  data  or  data  gleaned 
from  empirical  experiences  with  the  software;  regardless,  the 
system  would  enable  microcomputer  programmers  to  benefit  from 
existing  experience  with  and  information  about  microcomputer 
software  and  thereby  generate  more  efficient  code. 
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This  idea  is  aimed  at  supporting  the  microcomputer  progra 
ner ;  more  advanced  ideas  may  very  well  result  in  computer  gen¬ 
erated  software  in  the  nor  too  distant  future. 
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3.0  MICROCOMPUTER  SOFTWARE  DOCUMENTATION 


Without  effective  documentation  software  dies  a  slow  and 
painful  death.  Along  the  way  software  research  progress  is 
encumbered,  demonstrations  are  complicated,  and  technology 
transfer  is  undermined.  Interestingly,  while  the  disasterous 
effects  of  non-existent  or  poor  documentation  are  widely  veri¬ 
fiable,  few  are  willing  to  allocate  resources  aimed  at 
improving  documentation  techniques.  The  reason  is  simple: 
documentation  and  documentation  research  are  relatively  boring 
analytical  subtasks  connected  with  the  potentially  exciting 
design  and  development  of  microcomputer-based  systems. 

At  the  same  time,  some  effort  has  been  made  to  define  and 
improve  documentation  (see  Appendix  B) ,  and  given  the  progress 
recently  made  in  voice  input/output  system  development,  video 
technology,  interactive  graphics  technology,  and  computer- 
controlled  microfiche  systems  development,  it  is  now  possible 
to  experiment  with  the  development  of  several  variations  of 
unconventional  documentation  not  possible  just  five  years  ago. 
For  example,  systems  should  be  programmed  to  introduce  and 
explain  themselves  in  a  manner  not  unlike  that  which  is  used 
by  manufacturing  vendors.  Such  demonstrations  could  be  of 
invaluable  help  to  those  who  must  convinve  others  that  what 
they  have  developed  may  be  of  real  use.  Documentation  should 
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also  be  transformed  from  the  inanimate  to  the  animate.  Computer¬ 
generated  system  specifications  and  functional  descriptions  can 
be  of  immense  transfer  use,  as  can  on-line  users  manuals.  Simi¬ 
larly,  films  of  documentation  can  also  help  to  bridge  the  gap 
between  the  developer  and  the  user.  Here  computer-controlled 
fiche  could  be  used  to  minimize  cost,  time  delay,  and  obsolescence. 
Similarly  large  screen  display  systems  could  be  used  to  present 
complicated  documentation  "blueprints"  to  large  audiences  and 
program  conversion  teams  and  groups.  Self-documentation  and 
automatic  flowcharting  systems  should  also  be  developed.  Indeed, 
the  approach  now  taken  by  MIT  regarding  the  development  of  video¬ 
disc-based  training  systems  could  be  used  to  develop  videodisc- 
based  documentation  systems. 
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4.0  MICROCOMPUTER  SOFTWARE  EVALUATION 


Evaluating  microcomputer  software  can  be  exasperating.  In 
the  1970s--with  a  good  deal  of  DARPA  support,  however,  a  method¬ 
ology  was  developed  to  assist  decision  makers  with  complicated 
evaluation  problems.  The  methodology  was  subsequently  incarnated 
as  a  microcomputer  program  called  "EVAL." 

4 . 1  The  Evaluation  Methodology 

At  the  core  of  EVAL  lies  an  evaluation  methodology  known 
as  multi-attribute  utility  theory  (MAUT) .  Developed  at  the 
University  fo  Southern  California  by  Ward  Edwards,  MAUT  "can 
spell  out  explicitly  what  the  values  of  (a)  decision  maker  are, 
...and  show  how  much  they  differ"  (Edwards,  1977).  The  values 
themselves  are  determined  against  a  set  of  evaluative  criteria 
(or  attributes)  which  are  arranged  hierarchically  in  a  MAU  model. 
The  construction  of  a  MAU  model  thus  begins  with  "the  overall 
top-level  criterion  for  which  a  comparative  evaluation  score  is 
desired.  That  factor  is  successively  decomposed  into  its  com¬ 
ponent  criteria  in  descending  levels  of  the  hierarchy  such  that 
each  successive  lower-level  criterion  is  more  specific  than  those 
at  the  preceding  level..."  (Allardyce,  et  al.,  1979).  The  cri¬ 
teria  are  then  weighted  in  terms  of  their  importance  and  then 
the  decision  maker  scores  the  objects  under  evaluation  against 


4 . 2  EVAL 


f 


I  EVAL  is  a  generic  APL  program  which  currently  resides  on 

an  IBM  5110.  Through  EVAL,  a  decision-maker  can  create,  store, 
retrieve,  and  refine  MAU  models  interactively.  A  Typical  MAU 
model  appears  below. 


i  The  use  of  EVAL  is  fixed  according  to  the  following  ele- 

i 

i  ments  (see  Allardyce,  et  al.,  1979): 

«i 

4  ' 

•  The  Evaluation  Problem:  J. 

i 

A  label  identifying  the  problem; 

•  Criteria: 

»  -  A  set  of  evaluative  criteria  decomposed 

E  into  component  criteria;  j 

•  Alternatives:  j 

A  list  of  (labeled)  alternatives  which  J 

the  decision  maker  must  evaluate; 

•  Utility  Scores: 

!'  A  list  of  scores  (expressed  as  a  number 

between  0  and  1)  representing  the  relative 
utility  of  each  alternative  evaluated 
with  respect  to  each  (bottom-level) 
criterion ; 

•  Relative  Importance  Weights:  i 

Weights  which  describe  the  relative 
importance  of  lower-level  criteria. 

Al_l  criteria  (expect  for  the  overall 
/  top-level_7  criterion)  are  assigned 
*'  importance  weights; 
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•  Data  Identification  Numbers  (DINs) : 


These  are  assigned  to  each  criterion 
and  describe  how  the  criteria  are 
related.  This  numerical  labeling 
process  is  shown  in  the  following 
figure.  (For  example,  the  sub-criteria 
of  criterion  1  have  data  identification 
numbers  1.1  and  1.2.) 


The  above  input  specifications  can  then  be  processed  to 
yield  the  following  results: 


•  Overall  Results: 

The  overall  value  or  "worth"  associated 
with  each  alternative  obtained  by 
weighting  and  adding  the  value  scores 
assigned  to  the  bottom-level  criteria, 
aggregating  from  the  bottom  to  the  top; 

•  Normalized  Weights: 

A  set  of  vectors  corresponding  to  the 
relative  criteria  importance  weights; 

•  Intermediate  Results: 

Values  assigned  to  any  of  the  inter¬ 
mediate  criteria  as  they  contribute 
to  the  overall  results; 

•  Cumulative  Weights: 

Weights  corresponding  to  the  relative 
criteria  importance  weights  calculated 
as  follows:  "top-level  criteria  com¬ 
prising  the  overall  evaluation  have 
cumulative  weights  equal  to  their 
normalized  weights.  At  the  next  lower 
level,  the  criteria  are  assigned  a 
cumulative  weight  computed  by  multiplying 
the  normalized  weight  by  the  cumulative 
weight  of  the  factor  to  which  it  is 
attached,  and  dividing  the  product  by 
100.  This  process  is  continued  down 
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through  the  structure  until  all  criteria 
have  been  assigned  cumulative  weights. 

The  cumulative  weight  (CUMWT)  indicates 
the  relative  importance  of  the  criterion 
to  the  overall  evaluation"  (Allardyce, 
et  al. ,  1979) ; 

•  Sensitivity  Analysis: 

The  user  identifies  a  single  criterion 
of  interest  and  assigns  the  maximum 
and  minimum  cumulative  weights  that 
it  may  assume.  EVAL  then  varies  the 
cumulative  weight  of  the  criterion  in 
increments  of  one-tenth  of  the  difference 
between  the  maximum  and  minimum  weights, 
while  the  other  weights  in  the  model 
maintain  their  previously  assigned 
proportional  relationships  with  one 
another.  Generally,  the  alternative 
that  receives  the  highest  overall 
utility  will  change  as  the  criterion 
weight  is  incremented  from  W  .  to  Wmax _ 
The  changes  are  referred  to  Slnthreshold 
points ,  as  shown  below.  (Note  that  the 
alternative  having  the  highest  value 
is  designated  with  an  asterisk.) 


1.2  PERFORMANCE  CURRENT  CUMWT:  55.00 


WEIGHT 

A 

B 

C 

D 

E 

.0 

63 

54 

50 

68 

74* 

10.0 

63 

56 

52 

66 

73* 

20.0 

64 

59 

54 

64 

72* 

30.0 

64 

62 

56 

62 

71* 

40.0 

65 

64 

5*8 

60 

70* 

50.0 

65 

67 

60 

58 

69* 

60.0 

66 

70* 

62 

56 

68 

70.0 

66 

72* 

63 

54 

67 

80.0 

67 

75* 

65 

52 

66 

90.0 

67 

78* 

67 

49 

65 

100.0 

68 

81* 

69 

47 

64 

SENSITIVITY  ANALYSIS 
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4 . 3  A  Microcomputer  Software  Evaluation  System 


Boehm,  et  al.  (1977)  have  developed  a  software  character¬ 
istics  tree  which  has  been  converted  by  CSM  into  a  multi-attri¬ 
bute  utility  model  for  the  evaluation  of  software  quality.  Like 
all  EVAL  models  it  is  changeable;  nevertheless,  we  think  it  is 
probably  very  useful  as  is.  Also  like  all  EVAL  models  the 
criteria  have  been  defined  (according  to  Boehm,  et  al.,  1977); 


•  Accessibil ity :  Extent  to  which  code 
facilitates  use  of  its  parts; 

•  Accountability:  Extent  to  which  code 
can  be  measured; 

•  Accuracy:  Extent  to  which  the  output 
produced  by  code  are  sufficiently  precise 
to  satisfy  their  intended  use; 

•  Augmentability :  Extent  to  which  code 

can  be  expanded  in  computations  functions, 
or  data  storage  requirements; 

•  Availability:  Degree  to  which  a  system 
of  resource  is  ready  to  process  data. 
Availability.  MTBF/ (MTBF  +  MTTR) ; 

•  Communicativeness:  Extent  to  which  code 
facilitates  the  specifications  of  inputs 
and  provides  outputs  whose  form  and  con¬ 
tent  are  easy  to  assimilate; 

•  Completeness:  Extent  to  which  all  parts 
of  code  are  present  and  developed; 

•  Conciseness:  Extent  to  which  excessive 
information  is  not  present; 

•  Consistency:  Extent  to  which  code  con¬ 
tains  uniform  notation,  terminology,  and 
symbology  within  itself,  and  external 
consistency  to  the  extent  that  the  con¬ 
tent  is  traceable  to  the  requirements; 
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•  Device  independence:  Extent  to  which 
code  can  be  executed  on  computer  hard¬ 
ware  configurations  other  than  its 
current  one; 

•  Efficiency:  Extent  to  which  code  fulfills 
its  purpose  without  wasting  resources; 

•  Human  engineering:  Extent  to  which  code 
fulfills  its  purpose  without  wasting 
users'  time  and  energy  or  degrading  their 
morale ; 

•  Legibility:  Extent  to  which  function  is 
easily  discerned  by  reading  codes; 

•  Maintainability:  Extent  to  which  code 
facilitates  updating; 

•  Modifiability:  Extent  to  which  code 
facilitates  the  incorporation  of  changes; 

•  Portability:  Extent  to  which  code  can 
be  operated  easily  and  well  on  computer 
configurations  other  than  its  current  one; 

•  Reliability:  Probability  that  an  item 
(device  or  program,  system)  will  function 
without  failure  over  a  specified  time 
period  or  amount  of  usage; 

•  Robustness:  Extent  to  which  code  can 
continue  to  perform  despite  a  violation 
of  the  assumptions  in  its  specifications; 

•  Self-containedness:  Extent  to  which  code 
performs  its  explicit  and  implicit  functions 
within  itself  ; 

•  Self-descriptiveness:  Extent  to  which 
reader  of  code  can  determine  its  objectives, 
assumptions,  constraints,  inputs,  outputs, 
components,  and  revision  status; 

•  Testability:  Extent  to  which  code  facili¬ 
tates  establishment  of  verification  cri¬ 
teria  and  supports  evaluation  of  its 
performance ; 

•  Understandability :  Extent  to  which  purpose 
of  code  is  understandable  to  reader;  and 

•  Usability:  Extent  to  ..  .ich  code  is  reliable, 
efficient,  and  human-engineered. 
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As  presented  previously  (Wittmeyer,  1980),  the  Boehm,  et  al. 
(1977)  software  characteristics  tree  is  as  follows: 


Device-independence 

Self-containedness 

Accuracy. 

Completeness 

Robustness  Integrity 

Consistency 

Accountability 

Device  efficiency 

Accessibility 

Communicativeness 

Self-descnptiveness 

Structuredness 

Conciseness 

Legibility 

Augmentability 


When  this  tree  is  arranged  hierarchically  in  a  multi-attribute 
utility  model,  it  appears  as  follows: 
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CCOUNT\  /SELF-'' 

bility;  (contain 


5.0  CONCLUSION 


This  report  suggests  the  following: 


•  A  set  of  programming  standards  including 
especially  structured  programming  tech¬ 
niques,  should  be  developed  and  applied 
to  DARPA/DSO/CTD  projects; 

•  A  computer-based  production  rule  system 
should  be  developed  which  would  enable 
programmers  to  input  programming  require¬ 
ments  and  receive  guidance  and  recommen¬ 
dations  regarding  how  to  program,  which 
language  to  use,  and  the  like; 

•  Software  documentation  should  be  animated 
via  several  media  including  computer- 
based  fiche  and  videodisc  systems; 

•  Automatic  flowcharting  and  self-descriptive 
software  systems  should  be  developed  and 
tested  for  their  documentation  effective¬ 
ness  in  technology  transfer  contexts;  and 

•  Multi-attribute  utility-based  models  of 
software  quality  should  be  developed  and 
exercised  in  order  to  assess  existing 
and  improve  on-going  software  projects. 
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Structured  Programming 
and  Structured  Flowcharts 


Structured  programming  — that 
phrase,  unfamiliar  to  me  and,  1 
assume,  to  most  people  several  years 
ago— is  now  endowed  with  such 
magical  powers  that  most  books  on 
programming  include  it  somewhere  in 
their  titles. 

But  what  is  structured  program¬ 
ming?  Most  of  us  feel  that  it  is  prob¬ 
ably  good  for  us,  like  getting  regular 
exercise  or  brushing  our  teeth  after 
each  meal.  You  may  also  think  it's 
too  complicated  (not  true),  that  it 
slows  down  programming  (wrong,  it 
usually  speeds  it  up),  or  that  it  cannot 
be  done  unless  your  computer  runs  a 
language  like  Pascal  or  ALGOL 
(wrong  again). 

Simply  put,  structured  program¬ 
ming  is  a  set  of  techniques  that  makes 
programs  easier  to  write,  easier  to 
understand,  easier  to  fix,  and  easier 
to  change.  These  techniques  are  sim¬ 
ple  and  general  and  can  be  adapted  to 
any  computer  language  that  has  a 
goto  statement  — that  includes 
BASIC,  assembly  language,  FOR¬ 
TRAN,  and  COBOL.  The  purpose  of 
this  article  is  to  show  you  a  new  form 
of  notation  that  will  help  you  write 
structured  programs.  But  first,  let  s 
review  structured  programming. 

The  Elements  of  Structured  Pro¬ 
gramming 

A  structured  program  is  like  a  set 
of  notes  written  in  outline  form.  The 
headings  accompanied  by  Roman  nu¬ 
merals— I,  II,  III,  and  so  on— provide 
the  overall  organization.  Each  Roman 
numeral  topic  is  broken  into  several 
component  topics  (A,  B,  and  C,  for 
example)  and  each  of  these  is  sub¬ 
divided  further  (1,  2,  3,  ...)  and  fur¬ 
ther  (a,  b,  c,  ...)  as  needed.  Table  1 
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shows  a  problem  and  its  solution 
written  in  this  outline  form. 

The  above  example  demonstrates  a 
process  known  as  decomposition: 
breaking  a  task  (problem)  into  its 
subtasks.  This  process  represents  the 
most  important  concept  in  structured 
programming,  ie:  that  a  problem  can 
be  solved  by  repeatedly  breaking  it 
into  subproblems,  until  every  sub¬ 
problem  can  be  solved.  If  you  plan 
this  decomposition  before  you  try  to 
write  it  out  in  the  narrow,  precise, 
and  time-consuming  syntax  of  the 
target  language  (ie:  the  programming 
language  you  use  to  solve  the  prob¬ 
lem),  you  will  have  a  better  chance  of 
getting  your  program  right  the  first 
time. 


It  has  been 

mathematically  proven 
that  any  program  can 
be  written  using  three 
basic  constructs. 


But  how  do  you  decide  which  way 
to  break  the  problem  into  sub¬ 
problems?  Common  sense  helps.  Ask 
yourself,  "What  sequence  of  actions 
and  decisions  would  I  have  to  make  if 
I  were  doing  this  without  a 
computer?” 

The  rest  of  the  answer  comes  from 
the  literature  of  structured  program¬ 
ming.  It  has  been  mathematically 
proven  that  any  program  can  be  writ¬ 
ten  using  three  basic  patterns,  called 
programming  constructs  (or  simply 
constructs):  sequence,  if. ..then. ..else, 
and  while... do.  The  first  construct, 
sequence,  gives  you  the  basic  capa¬ 


bility  of  breaking  a  task  into  a  set  of 
subtasks  that  accomplish  the  main 
task  when  executed  sequentially.  j 

The  second  construct,  if... then...  j 
else,  performs  one  of  two  subtasks,  j 
depending  on  the  truth  or  falsity  of  a 
stated  condition.  An  everyday  exam¬ 
ple  of  this  construct  is  given  in  the 
following  sentence:  "If  it  is  raining 
outside,  1  will  take  my  umbrella  with 
me;  if  it  is  not,  I  will  leave  the  um¬ 
brella  at  home." 

The  third  and  least  familiar  con-  j 
struct,  while... do,  is  actually  a  I 
generalized  do-loop  that  repeats  a  set  | 
of  actions  (called  the  body  of  the  ] 
loop)  while  a  stated  condition  is  true,  j 
You  use  this  construct  when  making  j 
iced  tea  from  a  mix.  "As  long  as 
(while)  the  mix  is  not  completely 
dissolved,  I  will  continue  to  stir  it." 

If  you  combine  lines  of  code  in  the 
three  ways  described  above,  the  re¬ 
sulting  program  is  said  to  be  struc¬ 
tured.  In  most  languages  (BASIC,  for 
example)  you  will  still  use  goto 
statements,  but  they  will  be  restricted 
to  carrying  your  program  to  specific 
points,  ie:  the  beginnings  and  ends  of 
tasks  or  subtasks.  Each  module  (sub¬ 
task)  in  a  structured  program  has  a 
property  known  as  "one-in,  one-out"; 
that  is,  there  is  only  one  entrance  and 
one  exit  from  these  modules,  and  no 
module  will  ever  jump  into  the  mid¬ 
dle  of  another  one.  Instead  of  being 
like  a  plate  of  spaghetti,  a  program  is 
more  like  a  string  of  pearls  (with  each 
pearl  containing  another,  smaller 
string  of  pearls,  and  so  on);  each 
module  has  a  definite  and  unchanging 
position  on  the  string.  When  such 
regularity  can  be  counted  on,  existing 
modules  can  be  changed  or  deleted, 
and  entirely  new  modules  can  be  add- 
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ed  without  problems  caused  by  unex¬ 
pected  module  interaction. 

That  is  the  theory  of  structured 
programming— now  for  putting  it  in¬ 
to  practice.  Figures  1  thru  3  show  the 
three  constructs  (sequence,  if... 
then  ..else,  and  while  ..do)  in  stan¬ 
dard  flowchart  form  and  as  BASIC 
code.  (For  a  more  detailed  look  at 
writing  structured  programs  in 
BASIC,  see  "Applied  Structured  Pro¬ 
gramming,"  listed  in  the  references. 
This  article  appears  in  an  anthology 
that  contains  several  other  good  ar¬ 
ticles  on  program  decomposition  — 


sometimes  called  top-down  design  or 
programming  by  stepwise  refine¬ 
ment— and  structured  programming.) 

The  Origins  of  a  New  Notation 
When  I  got  my  first  job  as  a  com¬ 
mercial  programmer,  I  realized  that  I 
was  going  to  have  to  write  longer 
programs  than  I  had  previously  writ¬ 
ten.  This  prompted  me  to  adapt  struc¬ 
tured  programming  techniques  to  my 
work  in  BASIC,  COBOL,  and  RPG 
II.  (As  it  turned  out,  my  longest  pro¬ 
gram  was  a  35-page  COBOL  program 
that  grew  to  75  pages  without  going 


out  of  control.  I  could  not  have  done 
this  without  the  rigorous  use  of  struc¬ 
tured  programming  techniques.) 

As  my  programs  grew  larger,  I  be¬ 
came  dissatisfied  with  the  methods  I 
used  to  plan  my  programs.  Conven¬ 
tional  flowcharts  obscured  the  struc¬ 
ture  of  my  programs.  Nassi-Schnei- 
derman  charts  and  Wamier-Orr  dia¬ 
grams  were  unsatisfactory  for  other 
reasons. 

The  best  solution  offered  in  struc¬ 
tured  programming  texts  was  struc¬ 
tured  pseudocode,  an  informally 
written  Pascal-like  "program”  that 
uses  terse  English  phrases  to  describe 
the  program.  Listing  1  shows  the 
structured  pseudocode  for  the  pro¬ 
gram  outlined  in  table  lb.  I  used 
structured  pseudocode  extensively  to 
outline  programs  but  found  that  the 
details  of  the  resulting  pseudocode 
often  obscured  the  overall  design  of 
the  program. 

In  retrospect,  I  can  see  that  I 
wanted  a  design  notation  that  could 
do  the  following: 

•  Completely  describe  the  algorithm 
to  be  programmed 

•Provide  overview  and  detailed 
documentation  that  was  easy  to  read 

•  Not  need  to  be  redrawn  every  time 


Problem  Given  a  numeric  array  V  with  N 
elements,  find  the  largest  element.  MAXV, 
and  its  mde*.  MAXINDEX  These  variables 
are  related  as  follows 

•  i  <  MAXINDEX  <  N 

•  MAXV  =  V  (MAXINDEX) 

•  MAXV  is  the  largest  value  in  V(i) 
V(2).  V(N) 

Table  1:  A  problem  and  its  solution  in 
outline  form  The  common  outline 
form  used  for  summarizing  a  body  of 
materia!  can  also  be  used  to  give  struc¬ 
ture  to  the  emerging  design  of  a  pro¬ 
gram  Table  la  gives  a  statement  of  the 
problem  and  table  lb  gives  its  solution 
in  outline  form 


Solution 

I.  Set  problem  up 

A.  Set  MAXVAL  =  -9x  10“ 

B.  Set  MAXINDEX  =  0 
C  Set  INDEX  =  1 

II.  Find  largest  elemeni 

A.  Set  up  a  loop  that  increments  the 
variable  INDEX  from  the  beginning  to  the 
end  of  the  array  V 
For  each  value  of  INDEX 
1  Compare  the  current  array  value  (  V 
(INDEX)  )  to  MAXVAL 
a  if  MAXVAL  is  eouai  or  larger,  do 
nothing 

b  it  MAWAL  is  smaller,  replace  MAX¬ 
VAL  with  the  current  array  value  and 
MAXINDEX  with  the  current  index 
(the  value  of  INDEX) 

III  Print  the  largest  element  (MAXVAL)  and  its 
index  (MAXINDEX) 
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Listing  1:  A  structured  pseudocode  solution  of  the  FIN  DMA  X  problem  given  in  the  text 
and  in  table  1.  Structured  pseudocode  is  a  terse,  informal  Pascal-like  program  that 
helps  the  user  design  a  program  before  writing  it  in  a  formal  programming  language 
Program  F1HDMAX: 

Initialize  system  variables  (MAXV  ■  -9  x  10J°,  MAXINDEX  «  0.  INDEX  =  li 
While  INDEX  s  N 

find  value  of  current  array  element  (  CURRV  =  V  (INDEX'  ): 
if  current  array  element  (CURRV)  >  maximum  element  so  iar  (MAXV) 
new  maximum  element  «  current  element 
new  maximum  index  «  current  index  (  MAXINDEX  «  INDEX  ) 
endil 

increment  INDEX  by  1 
endwhile 

print  MAXV,  MAXINDEX 
(end  ol  program) 

Listing  2:  A  BASIC  implementation  of  the  FINDMAX  problem  from  table  1  In  this  pro¬ 
gram,  the  variable  MAXINDEX  has  been  shortened  to  M1NDEX  to  distinguish  it  from 
the  variable  MAXV.  This  program  is  written  in  TRS-80  Mode!  I  Level  1!  BASIC .  and  it 
will  run  on  other  computers  that  use  Microsoft  BASIC 


1  0> '  : 

no  REM  PROGRAM  FInDMfix 

1 D"  : 

i3<:>  pem  this  program  tai  es  an  array  of  numbers,  v.  and 

140  REM  FINDS  THE  LARGEST  ELEMENT.  MAXV.  AND  ITS  INDEX. 

15"  REM  MAXINDEX.  SUCH  THAT: 

1 60  REM  MAXV  =  V  (MAX  INDEX  I 

I  70  : 

1 80  REM  (FOR  THE  PURPOSES  OF  H LUSTRAT I  ON.  WE  WILL  ASSUMf 

1  R<:>  REM  THAT  THE  DATA  IS  ALREADY  IN  THE  AREA,  V.  • 

no  : 

rro  rem  ==================  main  program  ====================== 

230  * 

240  DIM  VUl't 

250  GOSUB  8<  REM  — NOT  FART  OF  ALGORITHM  IN  FIGURE  6;  THIS 
260  REM  SUBROUTINE  ENTERS  DATA  INTO  ARRAY  V 

27m  . 

280  REM - BOX  It  J  Nl  1 1 AL  I  7AT  J  ON  ROUTINE  - 

2*0  s 

300  MAXV  »  -9  *  1"C2" 

3-10  M  INDEX  =  O 
320  INDEX  =  1 

340  REM - BOX  2:  FIND  LARGEST  VALUE - 

350  s 

360  REM  —  (BEGINNING  OF  WHILE... DO  LOOP) 

370  IF  INDEX  N  THEN  520 
30"  CURRV  =  V  (INDEX) 

3-90  : 

400  IF  CURRV  MAXV  THEN  440 

410  MAXV  =  CURRV:  REM  --  (THIS  FART  EXECUTED  IF  FALSE) 

420  M INDEX  =  INDEX 

430  : 

440  INDEX  *  INDEX  +  1 

450  : 

460  REM  —  (JUMF  TO  BEGINNING  OF  WHILE... DO  LOOP) 

470  GOTO  370 
460  : 

490  : 

500  REM - BOX  3:  PRINT  FINAL  VALUES - 

510  x 

520  PRINT:  PRINT  "THE  LARGEST  VALUE  IN  THE  V  ARRAN  IS:" 

530  PRINT  "  V  ( "  x  M INDEX  ;  •• )  =  M ;  MAXV 


540  PRINT 
550  : 

560  END 

570  REM  =*=*=====*==*=  END  0^  MAIN  PROGRAM  =  =  =  *=  =  =  =  =  =  =  =:*=:«: =  =  =  =  = 
760  : 

770  : 

7Bm  REM - SUBROUTINE  TO  FILL  V  ARRAY - 

79m  : 

80*  •  DATA  12:  REM  (NUMBER  OF  ITEMS  TO  BE  READ  IN- 

81"  DATA  l,  15.  -26.  3.24.  -17.92.  O.  5,  1,  O,  21.4.  -205.  I? 

820  FEAP  N 

830  FOR  1=1  TO  N:  READ  V'l':  NEXT  I 
04"  RETURN 
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a  change  was  made  in  the  flowchart 
eUse  a  minimum  of  unfamiliar  nota¬ 
tion 

eBe  visually  pleasing 

This  structured  flowchart  notation, 
which  I  developed  over  a  period  of 
several  years,  meets  these  criteria. 

Basic  Constructs  in  Structured 
Flowcharting 

According  to  the  tenets  of  struc¬ 


tured  programming,  any  program 
can  be  expressed  as  a  combination  of 
four  basic  building  blocks.  These  are 
sequence,  if. ..then. ..else,  while... do, 
and  decomposition.  (The  first  three 
constructs,  described  in  < — ventional 
flowcharts  in  figures  la  thru  3a,  are 
given  in  structured  flowcharts  in 
figures  4a,  4b,  and  4c,  respectively.) 

The  sequence  construct  (figure  4a) 
is  identical  for  both  conventional  and 
structured  flowcharts;  however,  a 
later  construct,  decomposition,  will 
distinguish  the  structured  flowchart 
sequence  construct  from  its  conven¬ 
tional  counterpart. 


100  (BASIC  statement  tor  tubtask  1) 
1 10  (BASIC  statement  for  aubtask  2) 
120  (BASIC  statement  for  aubtask  3) 


Figure  1:  Sequence  as  a  control  structure.  Figure  la  shows  how  a  linear  sequence  of  sub¬ 
tasks  is  drawn  using  conventional  flowchart  notation  Figure  lb  shouts  the  equivalent 
sequence  as  a  series  of  BASIC  lines 


SUBTASK  DONE  IF 
CONDITION  IS  FALSE 


SUBTASK  DONE  IF 
CONDITION  IS  TRUE 


•  Fully  integrated  with  1 

•  Checkbook  manager 

•  Payables  manage' 

•  Expenses  statements 

Diskette  version 


dataKEY 


Our  tones'*  runt  with  Apol*  II  DOS  3  3  Or  Appteaoh 
or  language  System  and  it  compatible  with  Cornjs 
10  Mb.  S '  Sorrento  Valle  end  5  V. '  diskette,  menu- 
driven,  endtutonei 


TEL.  [803)485-7264  | 

(SSI  ESP  CDfTPULER 

stm  resources  re 

The  “full-sarvfca"  computer  company  I 

B  Ash  Btrsst  •  Hollis,  NH  03049 


(e)  CONVENTIONAL 


100  IF  (condition)  THEN  200 
120  (BASIC  statements  for  subtask 
done  If  condition  is  false) 


190  GOTO  300 

200  (BASIC  statements  for  subtask  done  if 
condition  it  true) 


299  (last  statement  of  "true"  aubtask) 
30C  (first  statement  of  next  construct) 


Figure  2;  The  if... then... else  construct  as  a  control  structure.  Figure  2a  shows  the  con 
ventional  notation  for  this  construct,  while  figure  2b  shows  the  BASIC  equivalent. 
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(a)  CONVENTIONAL 


riCONOITION) 

\  >  / 


SOOT  OF  LOOP 


IOC  IF  (opposne  of  cond'.v.or.'  THEN'  300 
110  (BASIC  statements  lo:  body  of  loop 
done  :f  ccr.dmcr.  is  true 


299  GOTO  100  Figure  4:  The  basic  structured  flowchart  notations  Figure  4a  shows  the  structured  flow- 

30.  (first  statement  of  nex t  constr-irv  chart  notation  for  a  sequence  of  tasks  it  is  equivalent  to  the  flowchart  of  figure  la 

Figure  4b  shows  the  structured  flowchart  notation  for  the  if. ..then,  else  construct 
Figure  3:  The  while.,  .do  loop  as  a  control  < equivalent  to  figure  2a);  note  that  it  is  the  placement  of  the  letters  T  and  F  'for  true  and 

structure  Figure  3a  sfiotrs  the  while  ..do  false)  that  determines  the  conditions  under  which  a  given  subtask  is  performed  Figure 

loop  in  conventional  flowchart  notation  4c  shows  the  structured  flowchart  notation  for  the  while  .  .do  construct  tequivalent  to 

Figure  3b  shows  the  equivalent  loop  in  figure  3ai  the  diagonal  line  leading  down  indicates  that  the  condition  fin  the  hexagon  is 

BASIC  code  performed  before  the  body  of  the  loop 


structure  Figure  3a  shows  the  while  ..do 
loop  m  conventional  flowchart  notation 
Figure  3b  shows  the  equivalent  loop  m 
BASIC  code 


The  if... then  . else  construct  is  fair¬ 
ly  straightforward  in  the  conven¬ 
tional  flowchart  (figure  2a).  In  the 
structured  flowchart  version  (figure 
4b).  the  boxes  to  be  performed  are  to 
the  right  of  the  decision  diamond, 
with  the  understanding  that  only  one 
of  the  two  boxes  will  be  performed 
based  on  the  value  of  the  condition  in 
the  diamond.  If  the  "else"  side  of  the 


construct  is  not  needed,  the  box 
labeled  F  is  eliminated.  In  this  case,  if 
the  condition  does  not  evaluate  to 
true,  no  action  is  performed,  and  con¬ 
trol  continues  with  the  next  construct 
following  the  decision  diamond. 

The  notation  for  the  while... do 
construct  is  not  as  easily  derived.  The 
conventional  flowchart  cannot  direct¬ 
ly  express  this  kind  of  loop;  it  must 


use  a  decision  diamond  and  an  exter¬ 
nal  loop  (figure  3a).  The  structured 
flowchart  version  (figure  4c)  intro¬ 
duces  a  new  symbol,  a  hexagon.  (Ac¬ 
tually,  the  hexagon  is  used  to  denote 
one  of  several  kinds  of  loop  struc¬ 
tures;  the  word  while  makes  this  a 
while... do  loop.)  The  box  connected 
below  and  to  the  right  of  the  hexagon 
is  performed  as  long  as  the  condition 
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Figure  S:  Example  of  the  subdivision  of  a  task  A  centra!  rule  of  structured  flowcharts  is 
that  any  box  can  be  broken  into  multiple  boxes  that  represent  the  necessary  subtasks 
Here,  task  X  is  broken  into  five  subtasks  executed  in  top-to-bottom  order  Subtask s  1 
2  and  5  are  simple  subtasks  Subtask  3  is  an  if  ...then...  else  construct  Subtask  4  is  a 
while,  do  loop 


listed  in  the  hexagon  is  true.  The  con¬ 
dition  is  performed  first  (denoted  by 
the  position  of  the  hexagon  being 
spatially  above  the  box  being  per¬ 
formed);  this  allows  the  possibility  of 
the  body  of  the  loop  being  performed 
zero  times  if  the  condition  is  initially 
false. 

The  fourth  and  pivotal  construct  of 
this  programming  notation,  decom¬ 
position,  can  best  be  stated  as  a  rule: 
any  box  representing  a  task  can  be 
broken  into  multiple  boxes  that  repre¬ 
sent  the  necessary  subtasks.  The  sub¬ 
tasks  may  be  rectangular  boxes  that 
represent  simple  tasks,  or  they  may 
be  any  other  valid  structured  flow¬ 
chart  construct  (if. ..then. ..else, 
while... do,  etc).  They  are  written  top 
to  bottom  in  the  order  of  perfor¬ 
mance,  with  the  line  denoting  pro¬ 
gram  flow  entering  each  subtask  box 
from  its  top  and  exiting  from  the  bot¬ 
tom. 

Figure  5  illustrates  the  above  con¬ 
struct.  Task  X  is  composed  of  five 
subtasks  performed  in  numeric  se¬ 
quence.  Tasks  1,  2,  and  5  are  simple 
subtasks.  Subtask  3  is  an  if... then... 
else  construct  that  allows  either  sub¬ 
task  3a  or  subtask  3b  to  be  per- 
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formed.  Sub  task  4  is  performed  as 
long  as  the  condition  within  the  hexa¬ 
gon  (B>Y)  is  true.  Of  course,  any 
subtask  box  may  be  further  divided 
into  its  component  subtasks. 

Since  any  box  can  be  broken  into 
component  subtasks,  you  can  now 
see  how  this  notation  is  used  to  design 
a  program.  The  boxes  in  the  leftmost 
column  give  the  overall  design  of  the 
program;  boxes  are  then  expanded  to 
the  right  as  each  box  (task)  is  divided 
into  boxes  representing  the  appropri¬ 
ate  combination  of  subtasks.  As  a 
result,  you  can  scan  any  one  of 
several  of  the  leftmost  column  of 
boxes  for  an  overview  of  varying 
depths  of  the  program  design,  or  you 
can  study  the  implementation  of  any 
major  or  minor  subtask  by  concen¬ 
trating  on  only  the  boxes  and  control 
structures  growing  to  the  right  of  the 
given  subtask. 

An  Example 

The  following  example  will  il¬ 


lustrate  the  process  of  developing  a 
program  using  structured  flowcharts. 
Using  the  example  of  table  la,  sup¬ 
pose  you  are  given  an  array  of  N 
numbers,  V(l),  V(2),...V(N),  and 
have  to  find  the  index  value  MAX- 
INDEX  such  that  the  largest  value  in 
the  V  array  is  MAXV  —  V  (MAX- 
INDEX).  The  entire  structured  flow¬ 
chart  for  this  problem  is  given  in 
figure  6. 

Cover  the  right  three-fourths  of  the 
flowchart  so  that  only  the  subtasks 
numbered  1,  2,  and  3  are  visible.  This 
is  what  the  "first  pass"  of  the  flow¬ 
charting  effort  should  look  like.  Sub¬ 
task  1  is  the  initialization  of  the  prob¬ 
lem.  Subtask  2  is  the  determination  of 
MAXINDEX  and  MAXV.  Subtask  3 
is  the  printing  of  these  two  values. 
Since  the  task  in  subtask  3  is  simple 
enough  to  be  directly  accomplished  in 
the  target  language  (for  example. 
BASIC),  it  need  not  be  subdivided. 

Subtasks  1  and  2  are  developed 
concurrently.  Subtask  2  is  basically  a 
loop  that  examines  V (1 ),  V(2),...V(N) 


far.  The  values  of  MAXV,  MAX- 
INDEX,  and  INDEX  must  be  set  (as  is 
done  in  subtasks  1.1,  1.2,  and  1.3). 
Note  that  this  loop  could  have  been 
done  more  easily  using  a  do-loop; 
other  optimizations  could  also  have 
been  made,  but  this  example  is  given 
for  the  purposes  of  illustration  only. 

The  main  work  for  each  element  is 
done  as  subtask  2.1.2:  if  the  current  V 
element  being  examined  (ierCURRV) 
is  greater  than  the  maximum  V  ele¬ 
ment  so  far,  MAXV  and  MAXINDEX 
are  set  to  the  current  array  and  index 
values,  respectively.  These  subtasks, 
numbered  2. 1.2.1  and  2. 1.2. 2,  are 
performed  only  when  the  relationship 
given  in  the  diamond  of  2.1.2  is  true. 

Once  the  structured  flowchart  has 
reached  the  level  of  detail  shown  in 
figure  6,  most  of  the  design  considera¬ 
tions  have  been  conceived  and  per¬ 
fected;  it  is  then  a  simple  task  to 
translate  the  program  into  BASIC 
(see  listing  2)  or  any  other  general- 
purpose  computer  language.  The 
benefits  are  more  pronounced  when 


INDEX*  INDEX  ♦  1 


MAX  INDEX  •  mDEx 


Figure  6:  Structured  flowchart  for  program  FINDMAX.  Given  an  array  V  with  N  elements,  the  problem  is  to  find  the  largest  element. 
MAXV.  and  its  index  within  the  V  array.  MAXINDEX.  The  numbers  above  each  box  give  the  sequence  and  level  of  that  box  in  rela¬ 
tion  to  the  entire  problem  For  example,  box  1  can  be  broken  into  three  subtask  boxes:  1.1.  1.2.  and  1.3. 
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2.1,  and  2.1.3  in  figure  6  can  be  re¬ 
placed  by  a  control  structure  that  is 
available  in  most  programming  lan¬ 
guages— a  do-loop  that  varies  INDEX 
from  1  to  N.  An  example  of  the  nota¬ 
tion  1  have  devised  for  this  is  given  in 
figure  7a;  the  body  of  the  loop  is  per¬ 
formed  according  to  the  parameters 
given  in  the  hexagon. 

Another  well-known  control  struc¬ 
ture  is  the  repeat... until  loop,  shown 
in  figure  7b.  The  position  of  the  body 


of  the  loop,  above  and  to  the  right  of 
its  associated  hexagon,  is  meant  to 
signify  that  the  body  of  the  loop  is 
performed  before  the  condition  is 
tested.  Although  the  meaning  of  this 
notation  does  not  implicitly  follow 
from  its  form,  it  was  chosen  for  its 
simplicity  and  consistency  with  the 
notation  already  developed. 

Other  constructs  come  to  mind:  a 
case  structure,  an  unconditional  goto, 
and  two  controlled  gotos— the  restart 


Figure  7:  Structured  flowchart  notation  for  a  do-loop  and  a  repeat... until  loop.  In  the 
do-loop,  figure  7a.  the  hexagon  contains  all  pertinent  information  defining  the  loop, 
and  in  the  form  most  comfortable  to  the  user  In  the  repeat... until  loop,  figure  7b.  the 
notation  is  interpreted  as  showing  the  body  of  the  loop  being  executed  before  the  condi¬ 
tion  is  tested  In  both  cases,  the  box  representing  the  body  of  the  loop  can  be  expanded 
to  the  right,  into  its  component  subtasks 
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(restart  the  innermost  containing 
loop)  and  the  exit  (go  to  the  first  task 
after  the  innermost  containing  loop). 
Although  1  have  used  some  of  these 
constructs  for  quite  some  time,  they 
are  not  presented  here  because  1  am 
not  yet  satisfied  with  the  notations  1 
have  developed  for  them.  In  any  case, 
structured  flowcharts  are  meant  to  be 
a  personal  notation— you  should  add 
to  and  modify  these  constructs  to  fit 
your  needs. 

Conclusions 

1  have  found  structured  flowcharts 
helpful  in  designing  programs.  The 
notation  is  obviously  intended  for 
weakly  structured  languages  (like 
BASIC),  as  its  utility  decreases  when 
the  structure  of  the  target  language 
increases. 

The  notation  is,  at  the  moment,  in¬ 
formal,  and  it  should  stay  that  way. 
It  should  be  extended  and  modified  in 
whatever  way  seems  useful  to  you.  In 
particular,  you  should  use  additional 
notation  for  special  features  of  the 
target  language  (eg:  global  and  local 
variables,  use  of  a  stack  of  inter¬ 
mediate  computation)  when  appli¬ 
cable.  If  the  structured  flowchart  is  to 
be  read  by  another  person,  however, 
you  should  define  all  the  structures 
used  in  terms  of  their  equivalent 
unstructured  (conventional)  flow¬ 
charts. 

If  the  final  structured  flowchart  is 
to  be  redrawn,  you  should  do  so  with 
clarity  in  mind.  Place  only  those 
boxes  that  help  explain  the  overall 
design  with  the  main  flowchart;  leave 
the  implementation  details  to  subor¬ 
dinate  flowcharts. 

I  hope  you  will  find  this  notation 
useful.  1  would  appreciate  your  sug¬ 
gestions,  criticism,  and  comments.  ■ 
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As  more  and  more  people  discover 
the  joys  of  owning  a  microprocessor 
the  need  for  good  documentation  will 
continue  to  grow.  Information  will  be 
needed  at  all  levels,  from  detailed 
hardware  and  software  documenta¬ 
tion  to  descriptions  of  which  buttons 
to  push  to  play  your  favorite  game. 

Who  will  provide  this  information? 
The  simple  answer  is  that  those  who 
know  will  tell  those  who  don't  know. 
1?  sounds  simple,  but  it's  not.  Every¬ 
where,  complaints  are  made  about 
documentation— "inadequate."  er¬ 
roneous,"  "over  my  head,"  "bad  or 
nonexistent,"  and  so  on.  All  too  of¬ 
ten,  companies  market  excellent  sys¬ 
tems  with  poor  or  sketchy  documen¬ 
tation,  resulting  in  unhappy  cus¬ 
tomers  and  unsatisfactory  sales. 

It's  a  common  mistake  to  believe 
that  because  somebody  is  an  expert  in 
a  subject,  he  can  explain  it  to  others. 
For  example,  it's  assumed  that  a  pro¬ 
fessor  who  knows  a  subject  inside  and 
out  can  pass  on  this  information  to 
students.  However,  whether  he  can 
or  cannot  depends  on  something  else 
besides  his  knowledge  of  the  subject. 
It  depends  on  his  ability  to  put 
himself  in  the  place  of  the  users,  the 
students,  to  begin  where  they  are, 


using  their  language  and  their  know¬ 
ledge  level.  (Of  course,  if  there  is  a 
failure  to  communicate,  it  is  the  stu¬ 
dents  who  fail,  not  the  professor!) 

The  microprocessor  industry  is  a 
classic  example  of  the  communication 
problem.  Aside  from  a  few  shining 
lights,  microprocessor  literature  suf¬ 
fers  from  a  bad  case  of  "the  jargons." 
The  problem  was  not  as  serious  while 
the  technology  was  being  pursued  by 
only  a  few  hobbyists,  who  like  to 
work  things  out  for  themselves.  Now 


Aside  from  a  few 
shining  fights, 
microprocessor 
literature  suffers  from 
a  bad  case  of  "the 
Jargons." 


that  the  public  is  becoming  involved 
in  large  numbers,  the  information 
must  adapt  to  the  customer,  not  the 
other  way  around. 

Many  could  undoubtedly  do  a 
better  job  of  communicating  if  they 
followed  a  few  principles.  But  doing 


this  requires  conscious  dedication. 
And,  of  course,  it  requires  principles. 
Those  principles  are  what  this  article 
is  about. 

To  translate  the  jargon  of  the  ex¬ 
pert  into  terms  meaningful  to  the  rest 
of  the  world,  we  need  an  interpreter. 
Such  an  interpreter  is  similar  to  the 
compiler  or  interpreter  used  in  com¬ 
puters,  which  translates  the  source 
language  into  one  the  machine  under¬ 
stands.  In  both  cases,  the  source 
language  is  provided  by  the  computer 
expert.  The  machine  is  the  user  in  one 
case,  the  public  in  the  other. 

Information  Design 

The  interpreter  we  require  can  best 
be  referred  to  as  information  design. 
This  term  is  better  than  the  common 
term  "technical  writing,"  in  that  it  in¬ 
dicates  what  really  is  re¬ 
quired — conscious,  step-by-step  de¬ 
sign.  Writing  is  just  one  aspect  of  pre¬ 
senting  understandable  information. 
In  fact,  technical  writing  is  similar  to 
writing  code  for  a  computer  program. 
If  the  planning  and  structure  are 
sound,  the  writing  almost  takes  care 
of  itself. 

There  are  many  aspects  of  informa¬ 
tion  design,  not  all  of  which  can  be 


•Content  defines  the  breadth  and 
depth  of  the  material  in  a  docu- 
-  merit,  and  is  best  specified  by  a 
topic  diagram.  Consistency  and 
j.  uniformity  of  treatment  are  re- 
\  treated  by  such  a  diagram:  One 
.  topic  should  not  be  treated  in  great 
detail  and  others  of  equal  impor¬ 
tance  hardly  mentioned.  The 
breadth  and  depth  should  fit  users' 
needs— all  relevant  material  in¬ 
cluded,  no  unnecessary  redundan¬ 
cies,  and  sufficient  detail  to  allow 
users  to  understand  the  explana¬ 
tion  or  perform  the  fob. 
•Organization  gives  shape  and 


Information  Design  Principles 

direction.  The  users  always  know 
where  they  are,  where  they  have 
been,  and  where  they  are  going. 
Indexes  and  headings  make  the 
organization  visible  to  users,  so 
that  information  is  located  easily 
and  quickly.  Material  is  grouped 
and  sequenced  to  flow  logically 
and  naturally  from  one  topic  to 
another.  A  top-down  approach  is 
used,  to  provide  on  overall  struc¬ 
ture  before  confusing  users  with 
details.  Introductions  and  sum¬ 
maries  tie  pieces  together  both  for¬ 
ward  and  backward,  and  reinforce 
for  long-term  memory. 


•Format  makes  the  information 
understandable  through  language 
and  illustrations.  Language  spems 
to  one  half  of  the  brain— the  ver¬ 
bal,  linear  side.  Simple  vocabulary 
and  short,  direct  sentences  make 
for  ease  of  understanding.  Illustra¬ 
tions  speak  to  the  other  half  of  (he 
brain— the  nonverbal,  spatial  side. 
Illustrations  are  most  effective 
when  they  ore  near  the  relevant 
text  and  are  keyed  to  it  through 
call-outs  and  highlights.  Working 
together,  words  and  illustrations 
present  the  whole  "picture"  as 
neither  can  alone. 
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covered  here.  What  is  necessary  is 
that  a  few  key  principles  are  made 
clear. 

The  basic  objective  of  information 
design  is  usability.  Whatever  the  user 
intends  to  do— write  a  program,  as¬ 
semble  a  piece  of  hardware,  learn 
how  a  system  works— the  documen¬ 
tation  must  serve  this  purpose. 

Although  this  may  sound  trivial,  if 
you're  writing  a  technical  document, 
it's  surprising  how  easy  it  is  to  lose 
sight  of  this  overall  requirement  after 
page  1.  The  presentation  can  become 
an  ego  trip  without  your  realizing  it. 
On  the  other  hand,  it's  hard  to  go 


wrong  if  you  consistently  keep  the  us¬ 
ability  objective  in  mind. 

How  do  we  determine  if  a  docu¬ 
ment  is  usable?  Whatever  the  type  of 
document— operator's  manual,  main¬ 
tenance  procedure,  reference  manual, 
training  program— it  has  some  pur¬ 
pose.  Its  purpose  may  be  to  explain  a 
concept,  describe  the  operation  of  a 
piece  of  equipment,  or  guide  a  person 
through  an  assembly  procedure. 

To  be  usable,  the  document  must 
take  the  users  from  a  state  of  in¬ 
complete  knowledge  about  some  sub¬ 
ject  to  a  condition  of  more  complete 
knowledge.  If  it's  a  procedure,  the  in¬ 


formation  must  guide  the  users 
through  the  task.  In  any  case,  the 
document  must  take  them  from 
"here"  to  "there." 

That's  what  information  design 
does:  It  starts  where  the  users  are  and 
builds  step  by  step.  The  information 
designer  first  esks  wh«  the  users  are. 
Then  he  puts  himself  in  their  place 
and  asks,  "What  will  they  under¬ 
stand,  with  their  experience?  What  is 
their  technical  knowledge  and 
vocabulary?  How  can  they  best  be 
helped?" 

Next,  he  builds  step  by  step.  He 
breaks  up  complicated  subjects  into 
simpler  parts.  He  leads  the  users 
gradually  into  new  territory,  helping 
them  make  their  own  discoveries. 
With  each  step  their  confidence  grows 
and  they  want  to  leam  and  do  more. 
At  the  end,  the  users  know  they  have 
succeeded— and,  therefore,  so  has  the 
information  designer. 

The  Elements  of  Information 
Design 

If  we  are  going  to  start  where  the 
users  are  and  build  step  by  step  we 
need  a  plan  of  action.  We  need  to 
decide: 

•what  information  to  include  ,n  the 
document 

•  how  to  organize  it 
•how  to  present  it  so  it  s  understand¬ 
able 

We'll  discuss  these  aspects  under  the 
headings  of  Content,  Organization, 
and  Format. 

Content 

The  content  of  a  document  is  the 
specific  technical  material  contained 
in  it.  This  should  be  carefully  defined 
by  boundary  lines  set  down  by  the  in¬ 
formation  designer. 

Content  really  has  two  aspects: 
what  information  is  included 
( breadth )  and  what  is  its  level  of 
detail  (depth).  A  simple  example  will 
illustrate  the  important  difference  be¬ 
tween  breadth  and  depth:  An  opera¬ 
tor's  manual  for  a  computer  system 
might  tell  you  to  "remove  and  replace 
the  printer's  print  wheel  as 
necessary."  The  subject  of  print  wheel 
replacement  is  thus  "covered"  in  the 
manual;  that  is,  in  terms  of  breadth, 
it  is  part  of  the  content.  However,  the 
lack  of  "how  to"  details  may  make 
this  information  of  little  use  to  many 
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printer  users.  Thus  the  proper  depth 
of  information  is  not  part  of  the  con¬ 
tent. 

A  good  tool  to  help  a  writer  of 
documentation  analyze  breadth  and 


depth  is  a  topic  diagram  (figure  1), 
which  is  an  arrangement  of  topics  in 
boxes  at  different  levels,  with  lines 
joining  related  topics.  It  serves  a  pur¬ 
pose  similar  to  that  of  an  outline,  but 


provides  an  easier  visual  check  on 
such  elements  as  breadth,  depth,  and 
consistency  of  treatment. 

In  figure  1,  topics  1  and  2  are  major 
topics  at  the  same  level  in  the 
diagram.  They  might  be  two  major 
components  of  a  system,  or  groups  of 
software,  or  procedures.  Neither  is  a 
subtopic  of  the  other  and  they  will  be 
treated  equally  in  the  presentation. 

Subtopics  are  shown  under  each 
major  topic:  1.1,  1.2, 1.3  under  topic 
1,  and  2.1  and  2.2  under  topic  2. 
These  represent  breakdowns  of  each 
major  topic.  The  diagram  can  con¬ 
tinue  on  down  to  further  depths  of 
subdivision  and  can  also  be  extended 
to  the  left  and  right  as  additional 
topics  are  added  at  a  given  level. 

We  can  see  that  the  breadth  of  the 
topic  diagram,  particularly  at  the  ma¬ 
jor  topic  level,  tends  to  indicate  the 
breadth  of  content.  The  depth  of  the 
diagram  indicates  the  depth  of  con¬ 
tent.  While  this  should  not  be  con¬ 
sidered  an  infallible  guide,  it  is  useful 
in  preliminary  planning. 

Another  use  of  a  topic  diagram  is 
that  it  gives  an  idea  of  consistency  of 
coverage.  A  glance  at  figure  1  will  tell 
the  writer  if  topics  at  the  same  level 
are  being  treated  with  some  con¬ 
sistency  in  how  they  are  subdivided, 
or  if  one  topic  is  being  pursued  to 
greater  levels  of  detail  than  others. 
Without  such  a  guide,  it's  easy  to 
cover  one  topic  in  great  detail  and 
give  other  topics  at  the  same  level  on¬ 
ly  token  treatment  or  overlook  them 
completely. 

Definition  of  content  is  as  impor¬ 
tant  for  what  is  not  included  as  for 
what  is.  Many  technical  documents 
include  irrelevant  information.  This 
can  be  particularly  annoying  in  pro¬ 
cedural  documents,  when  users  are 
trying  to  accomplish  an  exacting  task. 
They  want  to  get  on  with  it,  but  are 
continually  being  interrupted  with  ex¬ 
traneous  remarks  that  belong  in  some 
other  part  of  the  document  or  should 
be  left  out  entirely. 

Figure  2  shows  a  topic  diagram  for 
this  article.  As  you  can  see,  in  addi¬ 
tion  to  defining  content,  such  a 
diagram  shows  a  preliminary 
organization  or  structure. 

Organization 

To  proceed  step  by  step,  we  need  to 
know  where  we  are  going  and  a  route 
to  get  there.  In  other  words,  we  need 
structure,  or  organization.  Informa- 
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Figure  J:  A  topic  diagram  is  a  useful  tool  for  determining  the  breadth,  depth  and  con¬ 
sistency  of  a  piece  of  writing  Although  simitar  in  content  to  an  outline,  the  topic 
diagram  provides  a  clearer  visual  check  on  how  topics  are  handled  As  shown,  topics  1 
and  2  are  major  topics  at  the  same  level  Neither  is  a  subtopic  of  the  other  and  both  will 
be  treated  equally  when  the  writing  is  done.  Subtopics  represent  breakdowns  of  each 
major  topic  As  additional  topics  and  subtopics  are  added  the  diagram  can  extend 
downward  and  to  the  left  and  right 
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tion  must  be  grouped,  sequenced,  and 
related  in  order  to  be  understood. 
Otherwise,  it  is  merely  a  jumble  of 
disordered  facts  or  ideas— a  "shop¬ 
ping  list."  If  we  had  to  learn 
everything  by  rote  memory  from 
shopping  lists,  we'd  be  in  big  trouble. 
Once  a  good  structure  is  established, 
all  kinds  of  details  can  be  hung  on  it 
and  they  will  be  understood  and 
remembered. 

Organization  is  also  what  makes 
information  in  a  document  easily  ac¬ 
cessible.  Accessibility  depends  on 
both  the  overall  structure  of  the  docu¬ 
ment  and  how  this  structure  is  made 
visible  to  the  user  through  indexing 
and  headings.  If  information  is  organ¬ 
ized  properly,  the  user  will  be  able  to 
turn  quickly  to  the  information  he 
wants.  Once  there,  he  will  be  able  to 
continue  with  a  minimum  of  routing 
to  other  parts  of  the  document. 

The  importance  of  structure  or  or¬ 
ganization  can  be  illustrated  by  a 
very  simple  example — a  telephone 
book.  Have  you  ever  stopped  to 
think  how  useless  a  telephone  book 
would  be  if  the  names  were  listed  ran¬ 
domly  rather  than  alphabetically7 
The  important  aspects  of  structure  or 
organization  include  indexing  and 
headings,  grouping  and  sequencing, 
routing,  and  introductions  and 
reviews. 


Indexing  and  Headings 

Indexing  and  headings  are  the 
means  by  which  the  organization  of 
the  document  is  made  easily  visible  to 
users.  A  writer  may  actually  have  a 
good  organization,  but  if  it  is  not 
clear  to  users,  it  will  not  really  have 
served  its  purpose. 

Indexing  as  used  here  includes  both 
the  standard  type  of  index  found  at 
the  end  of  a  document  and  the  table 
of  contents.  The  index  should  be  set 
up  with  the  idea  that  users  will 
sometimes  look  for  items  alphabeti¬ 
cally,  as  in  a  dictionary.  Many  items 
that  are  too  small  or  too  specific  to  be 
included  in  the  table  of  contents  are 
made  accessible  with  a  good  index. 

Often  a  table  of  contents  can  be 
usefully  constructed  in  two  parts:  an 
overall  table  in  front  and  more  de¬ 
tailed  tables  with  each  major  section 
of  the  document.  This  avoids  an  un¬ 
wieldy  table  up  front.  Figure  3  pro¬ 
vides  an  example  of  a  two-part  table 
of  contents.  The  main  table  (on  the 
left  in  the  figure)  would  appear  in  the 
front  of  the  document.  Each  major 
section  would  start  with  its  own  table 
of  contents  (on  the  right  in  figure  3) 
showing  the  more  detailed  headings 
and  subheadings  in  the  section. 

A  consistent  set  of  headings  serves 
to  make  information  accessible. 
Headings  also  help  users  remember 


Figure  2:  A  topic  diagram  written  for  this  article. 
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where  they  are,  which  is  just  as 
important.  Thus  high-level  headings 
should  be  repeated  frequently,  for 
example  as  a  running  head  at  the  top 
of  each  page.  Having  the  relevant 
headings  always  in  front  of  the  user 
makes  the  structure  visible,  and  de¬ 
tails  are  then  assimilated  more  easily. 

Grouping  and  Sequencing 
The  overall  organization  of  the 
document  is  established  by  how  the 
content  material  is  grouped  and  se¬ 
quenced.  Again,  the  topic  diagram  is 


useful  during  the  planning  stages  in 
making  visible  the  planned  organiza¬ 
tion  of  the  document. 

Whether  the  document  is  pro¬ 
cedural  or  descriptive,  grouping  of 
the  topics  should  be  based  on  a 
logical  pattern  and  the  relevance  of 
different  items.  For  example,  pro¬ 
cedural  tasks  normally  performed 
together  (such  as  the  various  steps  re¬ 
quired  to  start  up  a  computer  system) 
should  be  grouped  together.  In  a 
system  description,  the  individual 
descriptions  of  system  components 


2  SYSTEM  COMPONENTS 

2  1  CENTRAL  PROCESSING  UNIT 
CONTROL  PANEL 
MICROPROCESSOR 
DIRECT  MEMORY  ACCESS 

2  2  DISK  DRIVES 

DRIVE  CONTROLS 
NUMBER  Of  DRIVES 
DRIVE  COMBINATIONS 

2  S  VIDEO  TERMINAL 

DISPLAY  SCREEN 
KEYBOARD 


Figure  3:  An  example  of  a  two-part  table  of  contents  By  using  an  overall  table  in  the 
front  of  the  document,  and  a  more  detailed  table  later,  an  initial  unwieldy  table  is 
avoided  where  a  user  would  be  subjected  to  unwanted  detail 


Figure  4:  Summaries  and  long-term  memory.  In  the  human  brain,  memory  is  divided 
into  short-term  memory  and  long-term  memory.  Although  the  capacity  of  long-term 
memory  is  large,  all  information  must  first  pass  through  a  short-term  memory.  When 
writing,  the  inclusion  of  summaries,  reviews,  and  question-and-answer  sections  is  an  ef¬ 
fective  way  of  passing  information  into  long-term  memory. 


would  normally  be  grouped  together, 
as  in  the  example  table  of  contents 
shown  in  figure  3. 

Sequencing  is  one  of  the  most 
critical  parts  of  the  structure.  The 
user  is  being  led  step  by  step  from  the 
known  to  the  unknown,  from  the 
simple  to  the  complex.  Here  the  top- 
down  structuring  principle  frequently 
used  in  writing  computer  programs 
also  applies.  The  sequence  should 
begin  at  the  top  and  give  the  readers 
the  big  picture  before  engulfing  them 
with  details.  It  is  not  unusual  to  begin 
reading  a  document  and  find  yourself 
up  to  your  ears  in  technical  details 
before  you  really  know  what's  going 
on. 

Most  equipment  operations  and 
human  activities  have  a  natural  or 
normal  sequence  that  should  be 
preserved  in  the  documentation.  For 
example,  you  normally  gather  to¬ 
gether  all  the  tools  and  supplies  re¬ 
quited  for  an  activity  before  starting, 
therefore,  this  information  should 
logically  precede  the  activity  descrip¬ 
tion.  It  is  disconcerting  to  have  to 
stop  in  the  middle  of  a  task  and  run  to 
the  hardware  store  to  buy  some  item. 

Routing 

Once  you  start  using  a  document  it 
is  inconvenient  to  have  to  refer  to 
other  parts  of  the  document,  or  to 
other  documents.  The  more  often  you 
are  routed,  and  the  more  pages  you 
have  to  thumb  through  to  get  there, 
the  less  useful  the  document.  On  the 
other  hand,  if  all  information  is 
repeated  at  each  point  of  need,  a 
bulky  document  can  result.  Obvious¬ 
ly,  judgment  is  required  in  weighing 
these  trade-offs.  For  example,  you 
wouldn't  want  to  tell  a  user  how  to 
solder  a  particular  type  of  joint  every 
time  it  came  up— you  would  set  aside 
a  special  section  for  this  purpose. 
However,  if  a  safety  precaution  ap¬ 
plies  to  a  number  of  different  tasks  in 
the  document,  it  is  better  to  accept 
the  redundancy  and  repeat  the 
precaution. 

Introductions  and  Reviews 

A  general  rule  is  to  prepare  users 
for  what  is  coming  and  to  remind 
them  of  where  they  have  been.  Pro¬ 
ceeding  through  a  document,  users 
may  forget  where  they  are,  forget 
what  has  gone  before— and  decide 
they  didn't  really  want  to  learn  this 
anyway.  Information  should  be 
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designed  to  help  users  relate 
backward  and  forward  and  recognize 
and  retain  key  points  along  the  way. 

Further,  readers  need  introductory 
instructions  to  help  them  find  and  use 
information.  For  example,  the 
numbering  schemes  for  tasks  or  il¬ 
lustrations,  the  use  of  safety  symbols, 
notes,  cautions,  and  warnings,  and 
die  treatment  of  information  about 
tools  and  supplies  should  be  briefly 
explained.  If  these  instructions  are 
backed  up  by  consistent  information 
presentation  (see  Format  section), 
users  will  quickly  leam  what  to  ex¬ 
pect,  no  matter  where  they  are  in  the 
document. 

Simple  reviews  at  key  points  rein¬ 
force  information  and  help  users  re¬ 


tain  it  in  memory.  Human  memory, 
to  put  it  simply,  consists  of  two  parts, 
"short-term”  and  "long-term.” 
Whereas  capacity  is  very  limited  in 
STM  (short-term  memory),  the 
capacity  of  LTM  (long-term  memory) 
is  large  indeed.  The  catch  is  that  in¬ 
formation  can  get  to  LTM  only 
through  STM.  Summaries  and  re¬ 
views  and  question-and-answer  ses¬ 
sions  are  effective  ways  of  establish¬ 
ing  information  firmly  in  LTM.  This 
important  concept  is  illustrated  in 
figure  4. 

Format 

Format  usually  has  the  rather  nar¬ 
row  meaning  of  "physical  layout  of 
the  page. "  Here  the  term  is  meant  also 


to  include  the  rules  that  govern  text 
and  illustrations— that  is,  how  infor¬ 
mation  is  presented  on  a  page. 

The  general  rule  is  that  language 
and  illustrations  should  work 
together.  Each  is  an  effective  way  of 
presenting  certain  kinds  of  informa¬ 
tion,  and  relatively  ineffective  for 
other  kinds.  When  combined  proper¬ 
ly,  they  form  a  powerful  presentation 
technique. 

People  will  readily  admit  that  pic¬ 
tures  can  do  things  that  words  cannot 
and  vice  versa.  And  yet  it  is  surpris¬ 
ing  how  often  we  find  ourselves 
reading  words,  words,  words,  when  a 
visual  or  two  would  have  helped  the 
presentation  considerably.  Many 
ideas  become  clearer  with  an  illustra- 
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tion,  and  some  kinds  of  information 
can  hardly  be  communicated  at  all 
without  one.  If  you  want  to  tell  some¬ 
one  what  something  looks  like,  show 
a  diagram  or  a  photograph. 

It  is  known  that  the  left  and  right 
sides  of  the  brain  are  quite  different . 
For  most  people,  the  left  side  is  domi¬ 
nant  and  works  mostly  with  linear, 
sequential  logic  (like  a  computer).  It 
is  also  the  verbal  side  and  controls 
language. 

The  right  side  specializes  in  images, 
music,  pictures— it  deals  in  spatial 
and  visual  concepts,  in  contrast  to  the 
linear,  verbal  left  brain.  Schools, 
with  their  traditional  emphasis  on 
verbal  skills,  have  tended  to  neglect 
the  right  side  of  the  brain.  People 
who  are  less  adept  with  their  left 
brain  have  suffered  as  a  result.  Ein¬ 
stein,  for  example,  was  a  poor  stu¬ 
dent  in  language,  but  had  a  great 
ability  to  visualize  (see  figure  5). 

The  ideal  combination  is  words 
and  pictures  working  together,  each 
doing  what  it  does  best.  In  a  pro¬ 
cedure,  for  example,  words  can  tell 
readers  what  to  do  and  how  to  do  it; 
pictures  can  tell  them  what  it  looks 
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Figure  S;  The  left  and  right  sides  of  the  human  brain  are  very  different.  In  most 
humans,  the  left  side,  which  works  mostly  with  linear  and  sequential  logic,  is  dominant 
The  left  side  also  controls  verbal  communications.  The  right  side  of  the  brain  deals  in 
spatial,  visual,  and  more  holistic  concepts  One  of  the  best  ways  of  imparting  informa 
tion  to  the  reader  is  through  a  combination  of  both  words  and  pictures,  thus  enabling 
the  reader  to  use  both  sides  of  the  brain 
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like  and  where  it  is.  For  descriptive 
material,  words  and  diagrams  will  do 
a  good  job  of  explaining  and  describ¬ 
ing,  provided  they  are  working 
together.  When  you  decide  to  use  pic¬ 
tures  to  communicate  with  readers, 
follow  the  flow  through  step  by  step. 
Don't  be  content  with  offering  an  oc¬ 
casional  "amazement  diagram"  and  a 
"see  figure  so-and-so."  You  can 
perhaps  wake  up  the  right  half  of  the 
reader's  brain  this  way,  but  to  get  it 
working  with  the  left  half  as  a 
unit— whole-brain  learning— make 
the  words  and  pictures  work 
together. 

Here  are  some  guidelines  on  how  to 
do  this,  discussed  under  the  following 
headings:  keying  text  to  illustrations, 
positioning  text  and  illustrations,  and 
limiting  information  density. 

Keying  Text  to  Illustrations 

The  mutual  reinforcement  of  text 
and  illustrations  can  be  strengthened 
by  keying  the  text  to  the  illustration. 
This  can  be  done  by  a  liberal  use  of 
highlights  and  call-outs,  which  are 
"talked  to"  in  the  text. 

For  complicated  diagrams,  an  in¬ 
dexing  system  can  be  used.  An  exam¬ 
ple  of  this  common  technique  is 
shown  in  figure  6.  Three  parts  of  an 
electrical  unit  are  designated  A,  B, 
and  C  in  the  picture  on  the  right. 
These  same  letters  are  used  in  the  text 
on  the  left  to  refer  to  these  specific 
parts.  This  method  can  be  used  with 
fairly  complex  diagrams  without  con¬ 
fusing  the  reader.  The  alphabetical  or 
numerical  symbols  take  up  little  room 
on  the  diagram  and  can  be  ordered 


(for  example,  clockwise  in  figure  6)  to 
make  it  easy  to  locate  any  symbol. 

Highlights  and  call-outs  help  the 
user  zero  in  on  the  main  items  of  in¬ 
terest  in  a  picture.  A  heavy  outline  or 
shading  or  color,  together  with  a  call¬ 
out  of  the  item  of  interest,  can  make 
the  text  and  illustration  mutually  sup¬ 
port  each  other  and  help  the  user 
relate  illustration  to  text. 

Consistent,  standard  nomenclature 
should  be  used  in  linking  text  to  il¬ 
lustration,  and  indeed  throughout  the 
document.  Information  becomes  less 
accessible  and  less  understandable  if 
the  same  item  is  referred  to  by  dif¬ 
ferent  names. 

Positioning  Text  and  Illustrations 

Because  the  text  and  related  pic¬ 
tures  should  work  together,  they 
should  be  positioned  close  together. 
Ideally,  the  user  should  be  able  to 
work  back  and  forth  between  text 
and  illustration  without  having  to 
turn  a  page.  While  this  ideal  is 
sometimes  impractical,  it  is  usually 
possible  to  keep  the  illustration  close 
to  the  relevant  text.  For  important, 
frequently  referenced  figures,  fold- 
outs  are  sometimes  the  answer. 

Limiting  Information  Density 

Information  is  like  food.  If  readers 
eat  too  fast,  or  too  much  at  one  time, 
they  get  indigestion.  If  information  is 
presented  too  fast  or  in  too  large 
doses,  readers  will  get  confused.  This 
is  because  of  the  limited  capacity  of 
short -term  memory.  Therefore,  like 
food,  information  must  be  broken  up 
into  "bite-size"  pieces  to  be  digestible. 


Figure  6:  Keying  text  to  illustrations.  The  mutual  reinforcement  of  text  and  illustrations 
(as  shown  in  figure  S)  can  be  strengthened  by  keying  the  text  to  the  illustrations  through 
the  use  of  highlights  and  call-outs  which  are  "talked  to"  in  the  text. 
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Good  format  does  this. 

Language  should  be  simple  and 
direct.  Only  words  the  reader 
understands  should  be  used,  with 
new  words  explained  as  they  are  in¬ 
troduced.  Explanations  are  easier  to 
read  and  understand  if  sentences  are 
short  and  simple,  and  if  words  have 
few  syllables. 

Illustrations  should  not  be  cluttered 
with  unnecessary  information.  If  they 
are  too  "busy,"  pictures  become  con¬ 


fusing  and  are  less  useful.  To  avoid  a 
profusion  of  details,  illustrations  can 
be  used  in  a  progression  from  simple 
to  more  complex.  This  is  related  to 
top-down  sequencing.  An  initial 
overall  figure  can  give  the  "big  pic¬ 
ture,"  which  is  easy  to  understand 
and  serves  as  a  beginning  structure 
for  proceeding  to  more  detailed  il¬ 
lustrations.  In  forming  such  progres¬ 
sions,  it's  important  to  preserve  the 
relative  locations  of  the  parts  of 
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whatever  is  being  pictured.  For  exam¬ 
ple,  if  a  simple  block  diagram  of  a 
microprocessor  leads  off  the  series, 
subsequent  more  detailed  diagrams 
and  schematics  should  show  the 
various  parts  of  the  blocks  in  the 
same  relative  positions  as  the  original 
block.  An  example  is  shown  in  figure 
7.  Note  that  the  lower  detailed 
diagram  preserves  the  relative  posi¬ 
tions,  established  by  the  upper  figure, 
of  the  major  parts  of  the  system. 

Earlier  we  said  that  microprocessor 
literature  is  suffering  from  a  bad  case 
of  "the  jargons."  However,  you'll  see 
by  now  that  there  is  much  more  to 
good  documentation  than  avoiding 
jargon.  You  probably  have  had  the 
experience  of  reading  something  and 
finding  that  it  was  very  difficult  to 
follow,  even  though  you  seemed  to 
understand  all  the  words.  In  this  case, 
the  author  managed  to  avoid 
technical  terminology  but  failed  in 
other  important  areas.  Good 
technical  documentation  requires  a 
highly  disciplined  approach,  and  that 
approach  is  provided  by  information 
design.  Those  who  adopt  a  go-as- 
you-please  approach  may  score  a  suc¬ 
cess  now  and  then,  but  it  will  be  by 
accident.  They  have  no  way  of  know¬ 
ing  whether  they  have  really  reached 
their  audience.  In  many  cases  they 
have  not.a 


Figure  7:  To  ovoid  reader  confusion,  illustrations  should  be  used  in  a  progression  from  less  detail  to  more  An  initial  block  diagram 
(7a)  can  give  the  overall  picture  before  going  into  greater  detail  (7b).  When  forming  these  progressions,  it's  important  to  keep  parts  in 
the  same  relative  positions. 


March  !«•!  C  BYTE  Publication*  Inc 


45 


